feat(analysis): enforce one canonical audio resource policy (#781) - #985

sequenceDiagram
  participant YouTube
  participant youtube.py
  participant audio_resource_policy
  participant ChordRecognizer
  YouTube->>youtube.py: 오디오 메타데이터 제공
  youtube.py->>audio_resource_policy: duration 검증
  audio_resource_policy-->>youtube.py: 승인 또는 정책 오류
  youtube.py->>audio_resource_policy: 다운로드 파일 크기 검증
  audio_resource_policy-->>youtube.py: 승인 또는 정책 오류
  ChordRecognizer->>audio_resource_policy: 디코딩 오디오 검증
  audio_resource_policy-->>ChordRecognizer: 승인된 버퍼 또는 정책 오류

• Fix all pre-merge checks with AI

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands.}

@opencode-agent Continue repair on the existing feat/canonical-audio-resource-policy-781 branch only. Exact current head is d2cf2047af790cddf02b3957856d246638a754b5 over protected develop@acdbea6344fe1231c39535b575f4de35e4c607c9. I already removed the current-head Ruff E501/Bandit B110 blockers in audio_metadata.py and formatted test_audio_metadata_preflight.py; do not revert or duplicate those repairs.

Verify each review finding against the exact current head before changing it, then repair only still-valid BandScope-owned defects with TDD:

1. ChordRecognizer.recognize() still uses if len(y) == 0: while current branch already contains RED regression tests/test_chord_recognizer_empty_layout_contract.py, which requires both (0, 2) and (2, 0) zero-element arrays to return []. Change the production emptiness predicate to shape-invariant y.size == 0; preserve non-empty validation semantics.
2. youtube.py now intentionally publishes canonical AudioResourcePolicyError.reason; validate_encoded_file_bytes(101 MiB) therefore emits encoded_file_too_large, but tests/test_youtube.py::test_download_youtube_audio_size_exceeded still asserts obsolete size_exceeded. Update only the stale contract assertion unless exact current desktop/IPC evidence proves the old code is still the published authority; do not weaken the policy reason contract just to satisfy the test.
3. The major metadata-preflight finding is still valid on this exact branch: audio_metadata.preflight_audio_metadata() exists, but temporal/analyzer.py, transcription/api.py, and separation/audio_separator.py still call librosa.load(... sr=..., mono=True, duration=...) without invoking the bounded source metadata preflight first. That permits source duration >15m, unsupported source sample rates, and >2 source channels to be transformed/truncated before post-decode validation. Add the smallest realistic integration REDs (including >15m rejected before librosa.load), then invoke the existing handle-based preflight before decode in each local decoder path, preserving post-decode validate_decoded_audio, payload-free policy errors, existing file-size bounds, and caller-owned handle rewind semantics. Do not add a second metadata authority.

Run focused tests plus repository-pinned Ruff/Bandit and canonical quickcheck. Do not touch or suppress inherited npm dependency findings (#783-owned), do not change foreign repositories, and do not resolve unrelated threads. Commit on this same branch and report the resulting exact head and evidence.

Ownership correction for the exact current lane: stop further source mutation on feat/canonical-audio-resource-policy-781 at d2cf2047af790cddf02b3957856d246638a754b5. Fresh whole-repo triage found the pre-existing canonical #781 owner is Draft #866 fix/audio-resource-policy-781, current head 223dd78126deeb3f12a68dc140f6a83fbe422225, created 2026-08-16 and deliberately stacked behind #865. #866 already owns the cross-boundary native desktop-core + desktop bridge + service request/decode + YouTube resource-policy contract, while this PR was created 2026-08-22 and changes only docs/analysis-engine files. Issue #781 explicitly requires desktop intake, IPC/orchestration, feature analyzers, decoded/memory/CPU/GPU budgets, cancellation measurements, and exact cross-boundary parity, so this PR must not continue as a competing policy authority or claim full closure.

Do not execute the prior repair request in comment 5382594823 on this branch. Its still-useful unique evidence is the source-container metadata preflight work (audio_metadata.py + regressions for source duration/rate/channels) and the shape-invariant chord empty-buffer regression; those will be evaluated/transplanted into canonical #866 only after exact-head compatibility review. Keep this PR open/unmerged for preservation until that unique work is accounted for; do not force-push, rebase, suppress gates, or modify foreign repositories.

Ownership freeze after fresh exact-head review.

Current #985 head is d2cf2047af790cddf02b3957856d246638a754b5 against develop@acdbea6344fe1231c39535b575f4de35e4c607c9. This lane overlaps accepted/canonical #781 owner #866 (fix/audio-resource-policy-781@223dd78126deeb3f12a68dc140f6a83fbe422225), which already owns the wider native desktop-core + renderer bridge + service admission + temporal/separation + YouTube resource boundary and is stacked on #865.

Do not continue parallel production writes on #985. Preserve this branch as reference evidence until its unique, still-valid work is reconstructed on #866 rather than merged/cherry-picked wholesale. The current unique evidence worth preserving is source-container preflight before transform/truncation, chord zero-element shape handling, transcription/chord policy coverage, and any reason-code regressions that remain compatible with #866's published error contract.

Fresh #985 CI also proves this is not ready independently: run 32598528823, job 97093124575, actual checkout 4ddab5242d591bc5733c5e3c9db9f4dfc72a4d4a fails first at mypy on the new direct soundfile import in audio_metadata.py, while current review additionally shows that preflight_audio_metadata is not wired to production and transformed/truncated audio can still hide original source duration/rate/channel metadata. Fixing only the import typing would therefore be symptom-only.

#866 already has an exact-head owner-control handoff to port the unique #985 evidence with RED→GREEN tests. Keep #985 unmerged and non-authoritative until that preservation is verified; close it only after exact semantic comparison proves no unique required behavior remains.

Preservation authority refresh: canonical #866 is now Draft exact fdb86972db71c47b71bcacef0ca7f6972299df9b. Besides retained Resource Admission/process protocol work, current ancestry now rejects multidimensional source-separation model output instead of flattening it into rehearsal evidence (RED 2cb1e648… → production 2d256a68…; doctoring 77e675aa…). #985 remains preservation-only at 071c1c84589397d565041f37515e39881718db98; do not copy this model/resource delta here. The still-unsuperseded capability is the M4A fallback requirement/evidence, which remains coupled to #1129 decoder/backend/license authority and must not be closed until that behavior is preserved through an admissible decoder boundary or the supported-format contract is explicitly changed.

#781 preservation refresh: canonical Resource Admission #866 is now exact a635df303dedb7830d0c89bef6beb75ed3307556, still Draft/unmerged on protected develop@314ddeae7b775a4957594b599358c8255617eb2e. New canonical delta since the head recorded in #985 is persisted feature-cache replay admission: exact deflated NPY member/header/sample/byte declaration preflight before NumPy materialization, then owned float32 + live AudioResourcePolicy revalidation before MIR reuse. This does not supersede #985's still-open M4A fallback requirement/evidence and should not be copied into #985. Artifact replay bounds also do not establish whole-process NumPy/zlib/RSS/decompression-time. docs/product-technical-gap-baseline.md is explicitly owned by #1116; #866 reverted an overlapping baseline edit and handed the semantic evidence to that owner.

Preservation authority refresh — #985 remains open/Draft at 071c1c84…; do not rewrite it onto mutable #866. Canonical #866 is now Draft exact 9d697fd3ee9ad189d3f7efaf2df56c09cc978c07. Its latest retained cache delta makes a disappearing persisted feature-cache sidecar fail closed (2eb80730… RED -> c7e8dfa9… production) and keeps the broader valid-generation metadata/archive replacement race explicitly unresolved. None of that supersedes #985's still-unsatisfied M4A fallback requirement/evidence, which remains coupled to commercial decoder/licensing owner #1129. No #866 source/tests should be copied here.

Preservation-lane refresh: canonical #866 has advanced to exact 2c462c7055ae014339b90711eadefcc72e843cce; #985 source remains exact 071c1c84589397d565041f37515e39881718db98 and is intentionally not rewritten onto mutable #866. The new #866 delta is persisted-cache availability/integrity work (synchronized canonical stem timelines plus fail-closed MemoryError/late EOF replay) and single-writer docs repair; it does not supersede #985's still-unproven M4A metadata/decoder fallback requirement.

Keep the M4A requirement/evidence open until #1129 / an approved decoder boundary proves equivalent supported-format behavior, subprocess/path/resource authority, and commercial license provenance. Do not copy current #866 cache/process source here.

Succession authority refresh: canonical #781 owner #866 is now exact 5c32fc6d29aa23cd631ccc1f66bf974beb1c74c2, still Draft. This current move is source-owned Ruff formatting only and does not supersede #985's remaining M4A/AAC fallback requirement. Keep #985 open/Draft and preserve its unique format-support evidence until #1129 plus the canonical Resource Admission path demonstrate an approved decoder boundary with equivalent rights-cleared Windows/macOS real-audio behavior. Do not copy mutable #866 cache/process source into this preservation lane.

Preservation metadata refresh only; keep #985 source 071c1c84589397d565041f37515e39881718db98 unchanged and Draft. Canonical #866 is now f1edee851897ee76b6b065466b4f30d5beaada59; its latest persistence repair also binds second-read persisted duration to the immutable cached stem timeline within half one sample (dfbf2884… RED → bbaf19a1… production). #985 must not copy that authority. Its M4A metadata fallback remains an unsuperseded requirement/evidence item until #1129 demonstrates an approved decoder/licensing boundary with equivalent Windows/macOS real-audio behavior or the supported-format contract is explicitly changed.

Preservation metadata refresh only; #985 source stays exact 071c1c84…. Canonical Resource Admission #866 is now Draft exact a9c827b6d6f7e3e09e7bfc4064209ddd08defbbd. Its latest replay repair rejects a second-read sidecar that changes feature-cache schemaVersion after the first API metadata admission (aa9265c7… RED → e0fbb030… production). Do not copy that archive owner here. The M4A fallback remains unsuperseded until #1129 resolves the concrete decoder/licensing/path/subprocess authority with equivalent rights-cleared real-audio evidence; this dependency refresh is not a basis to close #985.

Preservation check against canonical #866 exact ccda5980d8c40cab5a88c39148e19775c35e311d: this Resource Admission repair only makes persisted separation duration mandatory and timeline-consistent. It does not supersede #985's M4A metadata fallback requirement/evidence and does not resolve #1129's decoder/licensing boundary. Keep the unique M4A delta preserved; do not copy mutable #866 cache-admission source into this lane.

Preservation authority refresh only: canonical #866 is now Draft exact 8bcc20739ad8d9266feec3986a7c61f6c6a516fc. The new cache repair requires first- and second-read duration authority and prevents a later valid sidecar from repairing missing timing retained by the first metadata snapshot; #985 must not copy that persistence implementation. This does not supersede #985's unique M4A fallback evidence. Keep the fallback open until #1129 demonstrates a commercially approved decoder/backend with equivalent M4A/AAC behavior, path/subprocess/resource authority and license provenance, or the supported-format contract is explicitly changed. #985 source can remain untouched.

Fresh preservation handoff: canonical #781 writer #866 is now Draft exact 2fc82923e251a22d33d554ffc2fd041f1cc5bc05 on unchanged protected develop@314ddeae.... #985 source stays unchanged and must not copy mutable #866 cache/process code.

The M4A/AAC fallback remains a valid unsuperseded requirement until #1129 proves an approved decoder/licensing path with equivalent Windows/macOS real-audio evidence. Current #866 cache hardening and CI formatting repair do not satisfy that commercial decoder boundary, so no superseded-close claim is justified.

Preservation authority refresh: canonical #866 is now Draft exact 7a10f3cc8359ef44bfd52fbf31d7df287912d103; #985 source remains unchanged at 071c1c84589397d565041f37515e39881718db98. Current #866 additionally bounds the archive owner's persisted feature-cache metadata second read before UTF-8/JSON materialization; its first metadata snapshot remains an open same-owner gap. None of this supersedes #985's unique M4A metadata fallback requirement or #1129's concrete decoder/licensing evidence requirement. Do not close #985 or copy mutable #866 cache/parser source here.

Preservation update only; do not restack mutable source. Canonical #866 is now Draft exact 917860893addbe4dc4ae69e96e13b2f9f6e4eb74. It now carries native-verified source SHA-256 to the Python child, scopes persisted cache lookup under that digest, and validates the request before cache namespace transformation. This does not supersede #985's unique M4A metadata fallback requirement or resolve #1129 decoder/licensing evidence. Keep #985 Draft as preservation source until supported M4A behavior is either reproduced through an approved commercially admissible decoder boundary with equivalent real-audio evidence or explicitly removed from the product contract. Do not copy #866 cache/source authority into this lane.